JoSk
Simple package with similar API to native setTimeout
and setInterval
methods, but synced between all running NodeJS instances via MongoDB Collection.
Multi-instance task manager for Node.js. This package has the support of cluster or multi-thread NodeJS instances. This package will help you to make sure only one process of each task is running.
This is a server-only package.
Install:
npm install josk --save
var JoSk = require('josk');
import JoSk from 'josk';
Notes:
This package is perfect when you have multiple servers for load-balancing, durability, an array of micro-services or any other solution with multiple running copies of code when you need to run repeating tasks, and you need to run it only once per app, not per server.
Limitation - task must be run not often than once per two seconds (from 2 to ∞ seconds). Example tasks: Email, SMS queue, Long-polling requests, Periodical application logic operations or Periodical data fetch and etc.
Accuracy - Delay of each task depends on MongoDB and "de-synchronization delay". Trusted time-range of execution period is task_delay ± (1536 + MongoDB_Connection_And_Request_Delay)
. That means this package won't fit when you need to run a task with very certain delays. For other cases, if ±1536 ms
delays are acceptable - this package is the great solution.
API:
new JoSk({opts})
:
opts.db
{Object} - [Required] Connection to MongoDB, like returned as argument from MongoClient.connect()
opts.prefix
{String} - [Optional] use to create multiple named instancesopts.autoClear
{Boolean} - [Optional] Remove (Clear) obsolete tasks (any tasks which are not found in the instance memory (runtime), but exists in the database). Obsolete tasks may appear in cases when it wasn't cleared from the database on process shutdown, and/or was removed/renamed in the app. Obsolete tasks may appear if multiple app instances running different codebase within the same database, and the task may not exist on one of the instances. Default: false
opts.resetOnInit
{Boolean} - [Optional] make sure all old tasks is completed before set new one. Useful when you run only one instance of app, or multiple app instances on one machine, in case machine was reloaded during running task and task is unfinishedopts.zombieTime
{Number} - [Optional] time in milliseconds, after this time - task will be interpreted as "zombie". This parameter allows to rescue task from "zombie mode" in case when ready()
wasn't called, exception during runtime was thrown, or caused by bad logic. Where resetOnInit
makes sure task is done on startup, but zombieTime
doing the same function but during runtime. Default value is 900000
(15 minutes)opts.onError
{Function} - [Optional] Informational hook, called instead of throwing exceptions. Default: false
. Called with two arguments:
title
{String}details
{Object}details.description
{String}details.error
{Mix}details.uid
{String} - Internal uid
, suitable for .clearInterval()
and .clearTimeout()
opts.onExecuted
{Function} - [Optional] Informational hook, called when task is finished. Default: false
. Called with two arguments:
uid
{String} - uid
passed into .setImmediate()
, .setTimeout()
, or setInterval()
methodsdetails
{Object}details.uid
{String} - Internal uid
, suitable for .clearInterval()
and .clearTimeout()
details.date
{Date} - Execution timestamp as JS Datedetails.timestamp
{Number} - Execution timestamp as unix Number
Initialization:
MongoClient.connect(url, function (error, db) {
var Job = new JoSk({db: db});
});
Note: This library relies on job ID, so you can not pass same job (with the same ID). Always use different uid
, even for the same task:
var task = function (ready) {
ready();
};
Job.setInterval(task, 60*60*1000, 'task-1000');
Job.setInterval(task, 60*60*2000, 'task-2000');
Passing arguments (not really fancy solution, sorry):
var Job = new JoSk({db: db});
var globalVar = 'Some top level or env.variable (can be changed over time)';
var task = function (arg1, arg2, ready) {
ready();
};
var taskB = function (ready) {
task(globalVar, 'b', ready);
};
var task1 = function (ready) {
task(1, globalVar, ready);
};
Job.setInterval(taskB, 60*60*1000, 'taskB');
Job.setInterval(task1, 60*60*1000, 'task1');
Note: To clean up old tasks via MongoDB use next query pattern:
db.getCollection('__JobTasks__').remove({});
db.getCollection('__JobTasks__PrefixHere').remove({});
setInterval(func, delay, uid)
func
{Function} - Function to call on scheduledelay
{Number} - Delay for first run and interval between further executions in millisecondsuid
{String} - Unique app-wide task id
Set task into interval execution loop. ready()
is passed as third argument into function.
In this example, next task will not be scheduled until the current is ready:
var syncTask = function (ready) {
ready();
};
var asyncTask = function (ready) {
asyncCall(function () {
ready();
});
};
Job.setInterval(syncTask, 60*60*1000, 'syncTask');
Job.setInterval(asyncTask, 60*60*1000, 'asyncTask');
In this example, next task will not wait for the current task to finish:
var syncTask = function (ready) {
ready();
};
var asyncTask = function (ready) {
ready();
asyncCall(function () {
});
};
Job.setInterval(syncTask, 60*60*1000, 'syncTask');
Job.setInterval(asyncTask, 60*60*1000, 'asyncTask');
In this example, we're assuming to have long running task, executed in a loop without delay, but after full execution:
var longRunningAsyncTask = function (ready) {
asyncCall(function (error, result) {
if(error){
ready();
} else {
anotherCall(result.data, ['param'], function (error, response) {
waitForSomethingElse(response, function () {
ready();
});
});
}
});
};
Job.setInterval(longRunningAsyncTask, 0, 'longRunningAsyncTask');
setTimeout(func, delay, uid)
func
{Function} - Function to call on scheduledelay
{Number} - Delay in millisecondsuid
{String} - Unique app-wide task id
Set task into timeout execution. setTimeout
is useful for cluster - when you need to make sure task was executed only once.
ready()
is passed as third argument into function.
var syncTask = function (ready) {
ready();
};
var asyncTask = function (ready) {
asyncCall(function () {
ready();
});
};
Job.setTimeout(syncTask, 60*60*1000, 'syncTask');
Job.setTimeout(asyncTask, 60*60*1000, 'asyncTask');
setImmediate(func, uid)
func
{Function} - Function to executeuid
{String} - Unique app-wide task id
Immediate execute the function, and only once. setImmediate
is useful for cluster - when you need to execute function immediately and only once across all servers. ready()
is passed as the third argument into the function.
var syncTask = function (ready) {
ready();
};
var asyncTask = function (ready) {
asyncCall(function () {
ready();
});
};
Job.setImmediate(syncTask, 'syncTask');
Job.setImmediate(asyncTask, 'asyncTask');
clearInterval(timer)
Cancel (abort) current interval timer.
var timer = Job.setInterval(func, 34789, 'unique-taskid');
Job.clearInterval(timer);
clearTimeout(timer)
Cancel (abort) current timeout timer.
var timer = Job.setTimeout(func, 34789, 'unique-taskid');
Job.clearTimeout(timer);
Why JoSk?
JoSk
is Job-Task - Is randomly generated name by "uniq" project
Support this project:
This project wouldn't be possible without ostr.io.
Using ostr.io you are not only protecting domain names, monitoring websites and servers, using Prerendering for better SEO of your JavaScript website, but support our Open Source activity, and great packages like this one could be available for free.